<!doctype html>
<html lang="zh-CN">
<head>
  <base href="https://www.nodeapp.cn/timers.html" />
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width">
  <title>定时器（Timers） | Node.js 中文文档 | Node.js 中文网</title>
  <meta name="description" content="Node.js 是一个基于 Chrome V8 引擎的 JavaScript 运行环境。Node.js 使用了一个事件驱动、非阻塞式 I/O 的模型，使其轻量又高效。Node.js 的包管理器 npm，是全球最大的开源库生态系统。">
  <link rel="stylesheet" href="assets/style.css">
  <link rel="stylesheet" href="assets/sh.css">
  <link rel="canonical" href="https://www.nodeapp.cn/timers.html">
  <link rel="apple-touch-icon" href="apple-touch-icon.png">
  <link rel="icon" sizes="32x32" type="image/png" href="favicon.png">
  
  <script>
var _hmt = _hmt || [];
(function() {
  var hm = document.createElement("script");
  hm.src = "https://hm.baidu.com/hm.js?acdf78480f7f8f2b23b812565a5868e0";
  var s = document.getElementsByTagName("script")[0]; 
  s.parentNode.insertBefore(hm, s);
})();
</script>

</head>
<body class="alt apidoc" id="api-section-timers">
  <div id="content" class="clearfix">
    <div id="column1" data-id="timers" class="interior">
      <header>
        <h1>Node.js v8.x 中文文档</h1>
        <hr>
      </header>

      <div id="toc">
        <h2>目录</h2>
        <ul>
<li><span class="stability_2"><a href="#timers_timers">定时器</a></span><ul>
<li><span class="stability_undefined"><a href="#timers_class_immediate">Immediate 类</a></span></li>
<li><span class="stability_undefined"><a href="#timers_class_timeout">Timeout 类</a></span><ul>
<li><span class="stability_undefined"><a href="#timers_timeout_ref">timeout.ref()</a></span></li>
<li><span class="stability_undefined"><a href="#timers_timeout_unref">timeout.unref()</a></span></li>
</ul>
</li>
<li><span class="stability_undefined"><a href="#timers_scheduling_timers">预定定时器</a></span><ul>
<li><span class="stability_undefined"><a href="#timers_setimmediate_callback_args">setImmediate(callback[, ...args])</a></span></li>
<li><span class="stability_undefined"><a href="#timers_setinterval_callback_delay_args">setInterval(callback, delay[, ...args])</a></span></li>
<li><span class="stability_undefined"><a href="#timers_settimeout_callback_delay_args">setTimeout(callback, delay[, ...args])</a></span></li>
</ul>
</li>
<li><span class="stability_undefined"><a href="#timers_cancelling_timers">取消定时器</a></span><ul>
<li><span class="stability_undefined"><a href="#timers_clearimmediate_immediate">clearImmediate(immediate)</a></span></li>
<li><span class="stability_undefined"><a href="#timers_clearinterval_timeout">clearInterval(timeout)</a></span></li>
<li><span class="stability_undefined"><a href="#timers_cleartimeout_timeout">clearTimeout(timeout)</a></span></li>
</ul>
</li>
</ul>
</li>
</ul>

      </div>
<div id="apicontent">
        <h1>定时器<span><a class="mark" href="#timers_timers" id="timers_timers">#</a></span></h1>
<!--introduced_in=v0.10.0-->
<div class="api_stability api_stability_2"><a href="documentation.html#documentation_stability_index">稳定性: 2</a> - 稳定的</div><p><code>timer</code> 模块暴露了一个全局的 API，用于在某个未来时间段调用调度函数。
因为定时器函数是全局的，所以使用该 API 无需调用 <code>require(&apos;timers&apos;)</code>。</p>
<p>Node.js 中的计时器函数实现了与 Web 浏览器提供的定时器类似的 API，除了它使用了一个不同的内部实现，它是基于 <a href="https://nodejs.org/en/docs/guides/event-loop-timers-and-nexttick">Node.js 事件循环</a>构建的。</p>
<h2>Immediate 类<span><a class="mark" href="#timers_class_immediate" id="timers_class_immediate">#</a></span></h2>
<p>该对象是内部创建的，并从 <a href="timers.html#timers_setimmediate_callback_args"><code>setImmediate()</code></a> 返回。
它可以传给 <a href="timers.html#timers_clearimmediate_immediate"><code>clearImmediate()</code></a> 以便取消预定的动作。</p>
<h2>Timeout 类<span><a class="mark" href="#timers_class_timeout" id="timers_class_timeout">#</a></span></h2>
<p>该对象是内部创建的，并从 <a href="timers.html#timers_settimeout_callback_delay_args"><code>setTimeout()</code></a> 和 <a href="timers.html#timers_setinterval_callback_delay_args"><code>setInterval()</code></a> 返回。
它可以传给 <a href="timers.html#timers_cleartimeout_timeout"><code>clearTimeout()</code></a> 或 <a href="timers.html#timers_clearinterval_timeout"><code>clearInterval()</code></a> 以便取消预定的动作。</p>
<p>默认情况下，当使用 <a href="timers.html#timers_settimeout_callback_delay_args"><code>setTimeout()</code></a> 或 <a href="timers.html#timers_setinterval_callback_delay_args"><code>setInterval()</code></a> 预定一个定时器时，只要定时器处于活动状态，Node.js 事件循环就会继续运行。
每个由这些函数返回的 <code>Timeout</code> 对象都导出了可用于控制这个默认行为的 <code>timeout.ref()</code> 和 <code>timeout.unref()</code> 函数。</p>
<h3>timeout.ref()<span><a class="mark" href="#timers_timeout_ref" id="timers_timeout_ref">#</a></span></h3>
<div class="api_metadata">
<span>新增于: v0.9.1</span>
</div><p>调用时，只要 <code>Timeout</code> 处于活动状态就要求 Node.js 事件循环不要退出。
多次调用 <code>timeout.ref()</code> 没有效果。</p>
<p>注意：默认情况下，所有 <code>Timeout</code> 对象都是 &quot;ref&apos;d&quot; 的，通常不需要调用 <code>timeout.ref()</code>，除非之前调用了 <code>timeout.unref()</code>。</p>
<p>返回 <code>Timeout</code> 的一个引用。</p>
<h3>timeout.unref()<span><a class="mark" href="#timers_timeout_unref" id="timers_timeout_unref">#</a></span></h3>
<div class="api_metadata">
<span>新增于: v0.9.1</span>
</div><p>当调用时，活动的 <code>Timeout</code> 对象不要求 Node.js 事件循环保持活动。
如果没有其他活动保持事件循环运行，则进程可能在 <code>Timeout</code> 对象的回调被调用之前退出。
多次调用 <code>timeout.unref()</code> 没有效果。</p>
<p>注意：调用 <code>timeout.unref()</code> 会创建一个内部定时器，它会唤醒 Node.js 的事件循环。
创建太多这类定时器可能会对 Node.js 应用程序的性能产生负面影响。</p>
<p>返回对 <code>Timeout</code> 的一个引用。</p>
<h2>预定定时器<span><a class="mark" href="#timers_scheduling_timers" id="timers_scheduling_timers">#</a></span></h2>
<p>Node.js 中的计时器是一种会在一段时间后调用给定的函数的内部构造。
定时器函数何时被调用取决于用来创建定时器的方法以及 Node.js 事件循环正在做的其他工作。</p>
<h3>setImmediate(callback[, ...args])<span><a class="mark" href="#timers_setimmediate_callback_args" id="timers_setimmediate_callback_args">#</a></span></h3>
<div class="api_metadata">
<span>新增于: v0.9.1</span>
</div><ul>
<li><code>callback</code> 
            <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type">&lt;Function&gt;</a> 在 <a href="https://nodejs.org/en/docs/guides/event-loop-timers-and-nexttick">Node.js 事件循环</a>的当前回合结束时要调用的函数。</li>
<li><code>...args</code> <span class="type">&lt;any&gt;</span> 当调用 <code>callback</code> 时要传入的可选参数。</li>
</ul>
<p>预定立即执行的 <code>callback</code>，它是在 I/O 事件的回调之后被触发。
返回一个用于 <a href="timers.html#timers_clearimmediate_immediate"><code>clearImmediate()</code></a> 的 <code>Immediate</code>。</p>
<p>当多次调用 <code>setImmediate()</code> 时，<code>callback</code> 函数会按照它们被创建的顺序依次执行。
每次事件循环迭代都会处理整个回调队列。
如果一个立即定时器是被一个正在执行的回调排入队列的，则该定时器直到下一次事件循环迭代才会被触发。</p>
<p>如果 <code>callback</code> 不是一个函数，则抛出 <a href="errors.html#errors_class_typeerror"><code>TypeError</code></a>。</p>
<p><em>注意</em>：此方法具有可用<a href="util.html#util_util_promisify_original"><code>util.promisify()</code></a>提供的promises常用变体：</p>
<pre><code class="lang-js">const util = require(&apos;util&apos;);
const setImmediatePromise = util.promisify(setImmediate);

setImmediatePromise(&apos;foobar&apos;).then((value) =&gt; {
  // value === &apos;foobar&apos; (passing values is optional)
  // This is executed after all I/O callbacks.
});

// or with async function
async function timerExample() {
  console.log(&apos;Before I/O callbacks&apos;);
  await setImmediatePromise();
  console.log(&apos;After I/O callbacks&apos;);
}
timerExample()
</code></pre>
<h3>setInterval(callback, delay[, ...args])<span><a class="mark" href="#timers_setinterval_callback_delay_args" id="timers_setinterval_callback_delay_args">#</a></span></h3>
<div class="api_metadata">
<span>新增于: v0.0.1</span>
</div><ul>
<li><code>callback</code> 
            <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type">&lt;Function&gt;</a> 当定时器到点时要调用的函数。</li>
<li><code>delay</code> 
            <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type">&lt;number&gt;</a> 调用 <code>callback</code> 之前要等待的毫秒数。</li>
<li><code>...args</code> <span class="type">&lt;any&gt;</span> 当调用 <code>callback</code> 时要传入的可选参数。</li>
</ul>
<p>预定每隔 <code>delay</code> 毫秒重复执行的 <code>callback</code>。
返回一个用于 <a href="timers.html#timers_clearinterval_timeout"><code>clearInterval()</code></a> 的 <code>Timeout</code>。</p>
<p>当 <code>delay</code> 大于 <code>2147483647</code> 或小于 <code>1</code> 时，<code>delay</code> 会被设为 <code>1</code>。</p>
<p>如果 <code>callback</code> 不是一个函数，则抛出 <a href="errors.html#errors_class_typeerror"><code>TypeError</code></a>。</p>
<h3>setTimeout(callback, delay[, ...args])<span><a class="mark" href="#timers_settimeout_callback_delay_args" id="timers_settimeout_callback_delay_args">#</a></span></h3>
<div class="api_metadata">
<span>新增于: v0.0.1</span>
</div><ul>
<li><code>callback</code> 
            <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type">&lt;Function&gt;</a> 当定时器到点时要调用的函数。</li>
<li><code>delay</code> 
            <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type">&lt;number&gt;</a> 调用 <code>callback</code> 之前要等待的毫秒数。</li>
<li><code>...args</code> <span class="type">&lt;any&gt;</span> 当调用 <code>callback</code> 时要传入的可选参数。</li>
</ul>
<p>预定在 <code>delay</code> 毫秒之后执行的单次 <code>callback</code>。
返回一个用于 <a href="timers.html#timers_cleartimeout_timeout"><code>clearTimeout()</code></a> 的 <code>Timeout</code>。</p>
<p><code>callback</code> 可能不会精确地在 <code>delay</code> 毫秒被调用。
Node.js 不能保证回调被触发的确切时间，也不能保证它们的顺序。
回调会在尽可能接近所指定的时间上调用。</p>
<p>注意：当 <code>delay</code> 大于 <code>2147483647</code> 或小于 <code>1</code> 时，<code>delay</code> 会被设为 <code>1</code>。</p>
<p>如果 <code>callback</code> 不是一个函数，则抛出 <a href="errors.html#errors_class_typeerror"><code>TypeError</code></a>。</p>
<p><em>注意</em>：此方法具有可用<a href="util.html#util_util_promisify_original"><code>util.promisify()</code></a>提供的promises常用变体：</p>
<pre><code class="lang-js">const util = require(&apos;util&apos;);
const setTimeoutPromise = util.promisify(setTimeout);

setTimeoutPromise(40, &apos;foobar&apos;).then((value) =&gt; {
  // value === &apos;foobar&apos; (passing values is optional)
  // This is executed after about 40 milliseconds.
});
</code></pre>
<h2>取消定时器<span><a class="mark" href="#timers_cancelling_timers" id="timers_cancelling_timers">#</a></span></h2>
<p><a href="timers.html#timers_setimmediate_callback_args"><code>setImmediate()</code></a>、<a href="timers.html#timers_setinterval_callback_delay_args"><code>setInterval()</code></a> 和 <a href="timers.html#timers_settimeout_callback_delay_args"><code>setTimeout()</code></a> 方法每次都会返回表示预定的计时器的对象。
它们可用于取消定时器并防止触发。</p>
<p>不可能取消使用<a href="timers.html#timers_setimmediate_callback_args"><code>setImmediate()</code></a>，<a href="timers.html#timers_settimeout_callback_delay_args"><code>setTimeout()</code></a>的promisified变体创建的定时器。</p>
<h3>clearImmediate(immediate)<span><a class="mark" href="#timers_clearimmediate_immediate" id="timers_clearimmediate_immediate">#</a></span></h3>
<div class="api_metadata">
<span>新增于: v0.9.1</span>
</div><ul>
<li><code>immediate</code> <span class="type">&lt;Immediate&gt;</span> 一个 <a href="timers.html#timers_setimmediate_callback_args"><code>setImmediate()</code></a> 返回的 <code>Immediate</code> 对象。 </li>
</ul>
<p>取消一个由 <a href="timers.html#timers_setimmediate_callback_args"><code>setImmediate()</code></a> 创建的 <code>Immediate</code> 对象。</p>
<h3>clearInterval(timeout)<span><a class="mark" href="#timers_clearinterval_timeout" id="timers_clearinterval_timeout">#</a></span></h3>
<div class="api_metadata">
<span>新增于: v0.0.1</span>
</div><ul>
<li><code>timeout</code> <span class="type">&lt;Timeout&gt;</span> 一个 <a href="timers.html#timers_setinterval_callback_delay_args"><code>setInterval()</code></a> 返回的 <code>Timeout</code> 对象。 </li>
</ul>
<p>取消一个由 <a href="timers.html#timers_setinterval_callback_delay_args"><code>setInterval()</code></a> 创建的 <code>Timeout</code> 对象。</p>
<h3>clearTimeout(timeout)<span><a class="mark" href="#timers_cleartimeout_timeout" id="timers_cleartimeout_timeout">#</a></span></h3>
<div class="api_metadata">
<span>新增于: v0.0.1</span>
</div><ul>
<li><code>timeout</code> <span class="type">&lt;Timeout&gt;</span> 一个 <a href="timers.html#timers_settimeout_callback_delay_args"><code>setTimeout()</code></a> 返回的 <code>Timeout</code> 对象。 </li>
</ul>
<p>取消一个由 <a href="timers.html#timers_settimeout_callback_delay_args"><code>setTimeout()</code></a> 创建的 <code>Timeout</code> 对象。</p>

      </div>
    </div>

    <div id="column2" class="interior">
      <div id="intro" class="interior">
        <a href="/" title="Go back to the home page">
          Node.js 中文文档 | Node.js 中文网
        </a>
      </div>
      
        <!-- [start-include:_toc.md] -->
<ul>
<li><a href="documentation.html">关于本文档</a></li>
<li><a href="synopsis.html">用法与例子</a></li>
</ul>
<div class="line"></div>

<ul>
<li><a href="assert.html">断言测试</a></li>
<li><a href="async_hooks.html">异步钩子（Async Hooks）</a></li>
<li><a href="buffer.html">缓存（Buffer）</a></li>
<li><a href="addons.html">C++ 插件</a></li>
<li><a href="n-api.html">C/C++ 插件 - N-API</a></li>
<li><a href="child_process.html">子进程</a></li>
<li><a href="cluster.html">集群（Cluster）</a></li>
<li><a href="cli.html">命令行参数</a></li>
<li><a href="console.html">控制台（Console）</a></li>
<li><a href="crypto.html">加密（Crypto）</a></li>
<li><a href="debugger.html">调试器</a></li>
<li><a href="deprecations.html">废弃的 API</a></li>
<li><a href="dns.html">DNS</a></li>
<li><a href="domain.html">域（Domain）</a></li>
<li><a href="esm.html">ECMAScript 模块</a></li>
<li><a href="errors.html">错误（Errors）</a></li>
<li><a href="events.html">事件（Events）</a></li>
<li><a href="fs.html">文件系统</a></li>
<li><a href="globals.html">全局对象（Globals）</a></li>
<li><a href="http.html">HTTP</a></li>
<li><a href="http2.html">HTTP/2</a></li>
<li><a href="https.html">HTTPS</a></li>
<li><a href="inspector.html">检查工具（Inspector）</a></li>
<li><a href="intl.html">国际化</a></li>
<li><a href="modules.html">模块（Modules）</a></li>
<li><a href="net.html">网络（Net）</a></li>
<li><a href="os.html">操作系统（OS）</a></li>
<li><a href="path.html">路径（Path）</a></li>
<li><a href="perf_hooks.html">性能钩子（Performance Hooks）</a></li>
<li><a href="process.html">进程</a></li>
<li><a href="punycode.html">Punycode</a></li>
<li><a href="querystring.html">查询字符串</a></li>
<li><a href="readline.html">逐行读取</a></li>
<li><a href="repl.html">交互式解释器（REPL）</a></li>
<li><a href="stream.html">流（Stream）</a></li>
<li><a href="string_decoder.html">字符串解码</a></li>
<li><a href="timers.html">定时器（Timers）</a></li>
<li><a href="tls.html">安全传输层（TLS/SSL）</a></li>
<li><a href="tracing.html">事件跟踪（Tracing）</a></li>
<li><a href="tty.html">TTY</a></li>
<li><a href="dgram.html">UDP / 数据报</a></li>
<li><a href="url.html">URL</a></li>
<li><a href="util.html">工具集</a></li>
<li><a href="v8.html">V8</a></li>
<li><a href="vm.html">虚拟机（VM）</a></li>
<li><a href="zlib.html">压缩（ZLIB）</a></li>
</ul>
<div class="line"></div>

<ul>
<li><a href="https://github.com/nodejs/node">GitHub 仓库和问题跟踪</a></li>
<li><a href="https://groups.google.com/group/nodejs">邮件列表</a></li>
</ul>
<!-- [end-include:_toc.md] -->

      
    </div>
  </div>
  <script src="assets/sh_main.js"></script>
  <script src="assets/sh_javascript.min.js"></script>
  <script>highlight(undefined, undefined, 'pre');</script>
</body>
</html>
